/*
  Copyright (c) 2012 Vinícius dos Santos Oliveira

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
  */

/*!
  \page pluginsystem Tufão's plugin system

  \tableofcontents

  When you are developing web applications, usually you are faced with the
  problem of develop applications that will be running for years, without stop.
  Solutions in interpreted languages usually handle this problem by reloading
  the source file each time it changes. In C++, we can achieve a similar
  behaviour through plugins.

  Tufão provides the class Tufao::HttpPluginServer and a QtCreator's plugin to
  facilitate the integration of Qt plugins and Tufao::HttpServerRequestRouter.

  \section plugin-hello Understanding by example

  To help you understand the Tufão's plugin system, let's revisit the
  application created in \ref tufao-revisiting-hello. This application should be
  the same generated by the _application_ template, under Tufão QtCreator's
  plugin.

  \subsection plugin-pluginserver The Tufao::HttpPluginServer class

  The Tufao::HttpServerRequestRouter provides a robust request router interface
  and would be useful if we could tell it to use a plugin located in the file
  system as a handler. This is where Tufao::HttpPluginServer enters.

  Tufao::HttpPluginServer implements the Tufao::AbstractHttpServerRequestHandler
  interface, then you can use it as a handler in Tufao::HttpServerRequestRouter.
  Tufao::HttpPluginServer has its own set of mapping rules and handlers, but it
  will load its handlers from plugins.

  In the plugin server created previously, we pass a file in the constructor.
  This is how we set the plugins from Tufao::HttpPluginServer. This file can be
  edited using any text editor and Tufão will reload it when the file changes.
  See Tufao::HttpPluginServer::setConfig to learn how edit this file.

  \subsection plugin-user The plugin

  ![](qtcreator_pluginserver.png "The plugin template")

  Enough text! Let's create our plugin. First, you must open QtCreator, go to
  the new project dialog and select the _plugin_ template in the _Tufão Web
  Server project_.

  You'll get the following files:

    - *.pro: The name of this file depends on the name of the project. Tells
      qmake to use the _lib_ _TEMPLATE_ and the _plugin_ _CONFIG_.
    - plugin.h: Defines a class that implements the Tufao::HttpServerPlugin
      interface, needed by Tufao::HttpPluginServer.
    - plugin.cpp: Contains the implementation of Plugin members.

  The Tufao::HttpServerPlugin class is just a
  [factory](https://en.wikipedia.org/wiki/Factory_method_pattern) used by
  Tufao::HttpPluginServer to instantiate new handler objects. If you intend to
  create a plugin to be used by Tufao::HttpPluginServer, you must:

    1. Use Qt's plugin system
     1. Create a new qmake-based project
     2. Use _lib_ template and _plugin_ config
    2. Implement the Tufao::HttpServerPlugin interface in the plugin class (and
       don't forget the _Q_INTERFACES_ macro)
    3. Use Q_PLUGIN_METADATA to tell Qt about your plugin's metadata

  See Tufao::HttpServerPlugin for more details.

  \subsection plugin-config The glue!

  Finally we have:

    - An application supporting plugins
    - A plugin

  The only thing missing here is tell the application to use the plugin we
  created. To do that, we need:

    - Edit the config file used by the plugin server of our application. In the
      previous application, this file is any file named _routes.json_ placed in
      the application's working dir.

  Here is a basic one (adapt and use it):

  \include basic_routes.json

  When you ran your application, Tufão tried to find the _routes.json_ file and
  failed. Now you'll restart the application and the application will succeed to
  find the _routes.json_ file.

  After Tufão finds the _routes.json_ file, it will watch this file for changes
  and reload the plugins when it happens.

  \sa
  Tufao::HttpServerPlugin
 */
